Release 10.1A: OpenEdge Development:
Java Open Clients

Passing a ProDataGraph as INPUT or INPUT-OUTPUT

To pass a ProDataGraph for INPUT or INPUT-OUTPUT to an application service, you must as a minimum, create a ProDataGraph that maps to the corresponding ProDataSet parameter of the application service. While the mechanisms for programming an input ProDataGraph are identical regardless of the type of ProDataSet parameter it maps to, the requirements for preparing the ProDataGraph depend on the ProDataSet parameter passing mode, data type, and requirements of the application service.

To pass a ProDataGraph when the parameter passing mode of the ProDataSet is INPUT:
  1. Prepare the ProDataGaph as required. For more information, see the "Preparing an input ProDataGraph" section.

  2. Pass the ProDataGraph directly as a parameter to the proxy method.

To pass a ProDataGraph when the parameter passing mode of the ProDataSet is INPUT-OUTPUT:
  1. Prepare the ProDataGaph as required. For more information, see the "Preparing an input ProDataGraph" section.

  2. Create a ProDataGraphHolder object that includes a reference to the ProDataGraph. You can set the reference by using the constructor or by using the setProDataGraphValue() method on the holder object after you create it.

  3. Pass the ProDataGraphHolder as a parameter to the proxy method.

  4. Get the returned ProDataGraph from the ProDataGraphHolder using the getProDataGraphValue() method on the holder object and access it similar to an OUTPUT parameter. For more information, see the "Passing a ProDataGraph as OUTPUT" section.

    5. Note: For some application services, especially those that conform to the OERA, you might never have to prepare a ProDataGraph parameter with meta data. You might well receive the initial ProDataGraph as an application service OUTPUT parameter, update the ProDataGraph in your Java Open Client, and pass the modified ProDataGraph back to the application service as an INPUT-OUTPUT parameter without having to touch any meta data. For more information, see the "Updating a ProDataSet" section.

Preparing an input ProDataGraph

If the application service defines a DATASET (static ProDataSet) parameter, you must create a ProDataGraph that at least represents an empty ProDataSet and contains the meta data (ProDataGraphMetaData) that describes the temp-tables and data-relations defined for the 4GL static ProDataSet. There must be one ProDataObjectMetaData object for each temp-table and one ProDataRelationMetaData object for each DATA-RELATION object defined by the static ProDataSet. So, the meta data in the ProDataGraph must match the schema of the static ProDataSet in every particular.

Note: While you must define a ProDataGraph with all the meta data required to map a static ProDataSet schema, you can tell OpenEdge not to send temp-table schema information to the AppServer in order to optimize data transfer over the network. For more information, see the setNoSchemaMarshal() method in the "ProDataObjectMetaData class" section.

If the application service defines a DATASET-HANDLE (dynamic ProDataSet), you can pass a ProDataGraph with any or no meta data, including any or no ProDataRelationMetaData objects. As a minimum, you can pass a ProDataGraph with empty meta data (an empty ProDataGraphMetaData object), which produces an Unknown value (?) in the input DATASET-HANDLE. However, in practice, you must pass a ProDataGraph with meta data that represents the ProDataSet schema expected by the application service. So, most of the time, the programming for a ProDataGraph that maps to static or dynamic ProDataSet is identical.

For more information on the differences between static and dynamic ProDataSets, see OpenEdge Development: ProDataSets .

For a typical application, the general procedure for preparing a ProDataGraph for input is a two step process.

To prepare a typical ProDataGraph for input:
  1. Create and initialize a ProDataGraph object with its meta data.

  2. Create and add ProDataObject instances to the ProDataGraph.

Creating and initializing a ProDataGraph object with meta data

You can use a number of approaches for creating and initializing a ProDataGraph with meta data.

These approaches include two main variations:

  1. Start by creating the meta data and use it to create the ProDataGraph using the appropriate constructor.

  2. Start by creating a Java SDO DataGraph that conforms to the OpenEdge ProDataGraph object model, and create the ProDataGraph from this using the appropriate constructor.

The following procedure suggests just one such approach starting with the meta data. For information on creating an OpenEdge ProDataGraph from a Java SDO DataGraph, see the appropriate ProDataGraph constructor in the "ProDataGraph class" section.

To create and initialize a ProDataGraph with meta data:
  1. Create a ProDataGraphMetaData object using the constructor, where dataSetName is the 4GL name of the ProDataSet in the application service:

    2. Syntax 
    ProDataGraphMetaData(String dataSetName)

  2. Create a ProDataObjectMetaData object for each temp-table defined in the corresponding application service ProDataSet using the constructor:

    3. Syntax 
    ProDataObjectMetaData(int numFields, boolean bimageFlag,  
                      String tableName, String XMLNamespace,  
                      String XMLPrefix)

    The parameters specify, respectively:

    • The number of temp-table fields.
    • An indication if there is a BEFORE-TABLE defined for the temp-table (required in order to update the temp-table).
    • The 4GL name of the temp-table.
    • Any XML namespace (or null).
    • Any XML prefix (or null).

      • For more information, see the "ProDataObjectMetaData class" section.

  3. For each ProDataObjectMetaData object created in Step 2, add the column meta data to match the schema of a corresponding temp-table field. So, for each field in the temp-table, invoke this ProDataObjectMetaData method:

    4. Syntax 
    void setFieldMetaData(int fieldNumber, String fieldName, int extent,  
                      int proType, int userOrder, int xmlMapping,  
                      boolean isUnique)

    The parameters specify, respectively:

    • The 1-based number of the temp-table field.
    • The 4GL field name.
    • If an array field, a value greater than 1 indicating the extent.
    • A value specified by a class constant defined in com.progress.open4gl.Parameter that indicates the 4GL data type of the field. For more information, see the information on specifying data type meta data for temp-tables in Chapter 4, " Passing Parameters."
    • A 0-based user position order for the field.
    • An XML serialization value for later use, currently set to 0.
    • An indication if the field is a primary unique index for the temp-table.

      • For more information on creating table meta data, see the "ProDataObjectMetaData class" section.

  4. Add each ProDataObjectMetaData object completed in Step 3 to the ProDataGraphMetaData object created in Step 1 using this ProDataGraphMetaData method:

    5. Syntax 
    void addTable(ProDataObjectMetaData tablemd)

  5. For each DATA-RELATION object defined for the ProDataSet in the application service, create a corresponding ProDataRelationMetaData object using the constructor:

    6. Syntax 
    ProDataRelationMetaData(String name, ProDataObjectMetaData parent, 
                        ProDataObjectMetaData child) 
ProDataRelationMetaData(String name, int parentIdx, int childIdx,  
                        int numPairs, String pairsList, )

    The second constructor allows you to set foreign-primary key relationships for one or more columns between parent and child tables explicitly. The parentIdx and childIdx correspond to indexes into the list of table names returned by the ProDataGraphMetaData method, getTableNames(). You can also set these relationships in the instantiated ProDataRelationMetaData object using the overloaded setColumns() methods.

    For more information on creating data-relations, see the "ProDataRelationMetaData class" section.

  6. Add each ProDataRelationMetaData object completed in Step 5 to the ProDataGraphMetaData object created in Step 1 using this ProDataGraphMetaData method:

    7. Syntax 
    void addDataRelation(ProDataRelationMetaData drmd)

  7. Create the ProDataGraph from the ProDataGraphMetaData object completed in Step 4 and Step 6 using this constructor:

    8. Syntax 
    ProDataGraph(ProDataGraphMetaData dgmd)

For more information on creating meta data for a ProDataGraph, see the "ProDataGraphMetaData class" section.

Adding data to a ProDataGraph

Once you have the ProDataGraph defined with its meta data, you can create and add the rows to the various tables (ProDataObject lists) and generate all the data-relation references between them to complete the ProDataGraph. You can add data to a ProDataGraph in different ways. The following procedure assumes that you know the 4GL names of the temp-tables and fields and the field data types in the corresponding ProDataSet.

To add data to a ProDataGraph:
  1. For each row you want to add to a temp-table, create a ProDataObject using this ProDataGraph factory method, where tableName is the temp-table name:

    2. Syntax 
    ProDataObject createProDataObject(String tableName)

  2. For each ProDataObject that you create, add the column property data using one of these ProDataObject methods, where name is the 4GL name for the corresponding temp-table field:

    • To set the value of a single-valued property, use this method, where DataType is the full Java classname or intrinsic type name of the property data type and DataTypeName is a name that closely matches the data type name for the value:

      • Syntax 
       void setDataTypeName(String name, DataType)

      To identify the Java data type or class of the column property that maps to the 4GL data type of the temp-table field, see Table 5–3. For example, the following two methods set values for an int property (mapped to an INTEGER field) and a BigDecimal property (mapped to a DECIMAL field):

      Syntax 
      void setInt(String name, int) 
void setBigDecimal(String name, java.math.BigDecimal)

    • To set the value of a many-valued property (which maps to a temp-table array field), use this method, after loading the java.util.List object with the required values:

      • Syntax 
      void setList(String name, java.util.List)

      The values in the List all have the data type of the column property.

    • To set the value of a column property in the form of the java.lang.Object class, use this method:

      • Syntax 
      void set(String name, java.lang.Object)

      The value in the Object has the data type of the column property or java.util.List if the property is many-valued.

      You can also set the values of column properties with overloaded versions of these methods that index into the ProDataObject property list. For more information on determining the index of a column property and other information about column properties of a ProDataObject, see the "Using Java SDO classes to access Property meta data" section.

  3. Add each ProDataObject, dataObj, filled with data in Step 2 to the ProDataGraph using this ProDataGraph method:

    4. Syntax 
    void addProDataObject(ProDataObject dataObj) 
void addProDataObject(int index, ProDataObject dataObj)

    This method adds the ProDataObject to the collection (ProDataObject list) identified by its defined table name. Using an index, you can insert the ProDataObject at a location in the list. Otherwise, the object is added to the end of the list.

  4. Once all the tables (ProDataObject lists) have been populated with rows of data in Step 3, generate the parent-child ProDataObject references specified by all the ProDataRelationMetaData objects contained in the ProDataGraph using the following ProDataGraph method:

    5. Syntax 
    void setChildTableReferences()

    You can also generate these references one table at a time using overloads of this method. However, this is the most efficient method to generate data-relation references for a fully populated ProDataGraph.

For more information on methods for building ProDataGraphs, see the "ProDataGraph class" section.

Copyright © 2005 Progress Software Corporation
 www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095